<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>-X - Perldoc Browser</title>
    <link rel="search" href="https://perldoc.perl.org/opensearch.xml" type="application/opensearchdescription+xml" title="Perldoc Browser">
    <link rel="canonical" href="https://perldoc.perl.org/functions/-X">
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/stackoverflow-light.min.css" integrity="sha512-cG1IdFxqipi3gqLmksLtuk13C+hBa57a6zpWxMeoY3Q9O6ooFxq50DayCdm0QrDgZjMUn23z/0PMZlgft7Yp5Q==" crossorigin="anonymous" />
    <style>
      body {
        background: #f4f4f5;
        color: #020202;
      }
      .navbar-dark {
        background-image: -webkit-linear-gradient(top, #005f85 0, #002e49 100%);
        background-image: -o-linear-gradient(top, #005f85 0, #002e49 100%);
        background-image: linear-gradient(to bottom, #005f85 0, #002e49 100%);
        filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#ff005f85', endColorstr='#ff002e49', GradientType=0);
        background-repeat: repeat-x;
      }
      .navbar-dark .navbar-nav .nav-link,
      .navbar-dark .navbar-nav .nav-link:focus { color: #fff }
      .navbar-dark .navbar-nav .nav-link:hover { color: #ffef68 }
      #wrapperlicious {
        margin: 0 auto;
        font: 0.9em 'Helvetica Neue', Helvetica, sans-serif;
        font-weight: normal;
        line-height: 1.5em;
        margin: 0;
        padding: 0;
      }
      #wrapperlicious h1 { font-size: 1.5em }
      #wrapperlicious h2 { font-size: 1.3em }
      #wrapperlicious h3 { font-size: 1.1em }
      #wrapperlicious h4 { font-size: 0.9em }
      #wrapperlicious h1, #wrapperlicious h2, #wrapperlicious h3,
      #wrapperlicious h4, #wrapperlicious dt {
        color: #020202;
        margin-top: 1em;
        margin-bottom: 1em;
        position: relative;
        font-weight: bold;
      }
      #wrapperlicious a { color: inherit; text-decoration: underline }
      #wrapperlicious #toc { text-decoration: none }
      #wrapperlicious a:hover { color: #2a2a2a }
      #wrapperlicious a img { border: 0 }
      #wrapperlicious :not(pre) > code {
        color: inherit;
        background-color: rgba(0, 0, 0, 0.04);
        border-radius: 3px;
        font: 0.9em Consolas, Menlo, Monaco, monospace;
        padding: 0.3em;
      }
      #wrapperlicious dd {
        margin: 0;
        margin-left: 2em;
      }
      #wrapperlicious dt {
        color: #2a2a2a;
        font-weight: bold;
        margin-left: 0.9em;
      }
      #wrapperlicious p {
        margin-bottom: 1em;
        margin-top: 1em;
      }
      #wrapperlicious li > p {
        margin-bottom: 0;
        margin-top: 0;
      }
      #wrapperlicious pre {
        border: 1px solid #c1c1c1;
        border-radius: 3px;
        font: 100% Consolas, Menlo, Monaco, monospace;
        margin-bottom: 1em;
        margin-top: 1em;
      }
      #wrapperlicious pre > code {
        display: block;
        background-color: #f6f6f6;
        font: 0.9em Consolas, Menlo, Monaco, monospace;
        line-height: 1.5em;
        text-align: left;
        white-space: pre;
        padding: 1em;
      }
      #wrapperlicious dl, #wrapperlicious ol, #wrapperlicious ul {
        margin-bottom: 1em;
        margin-top: 1em;
      }
      #wrapperlicious ul {
        list-style-type: square;
      }
      #wrapperlicious ul ul {
        margin-bottom: 0px;
        margin-top: 0px;
      }
      #footer {
        font-size: 0.8em;
        padding-top: 0.5em;
        text-align: center;
      }
      #more {
        display: inline;
        font-size: 0.8em;
      }
      #perldocdiv {
        background-color: #fff;
        border: 1px solid #c1c1c1;
        border-bottom-left-radius: 5px;
        border-bottom-right-radius: 5px;
        margin-left: auto;
        margin-right: auto;
        padding: 3em;
        padding-top: 1em;
        max-width: 960px;
      }
      #moduleversion { float: right }
      #wrapperlicious .leading-notice {
        font-style: italic;
        padding-left: 1em;
        margin-top: 1em;
        margin-bottom: 1em;
      }
      #wrapperlicious .permalink {
        display: none;
        left: -0.75em;
        position: absolute;
        padding-right: 0.25em;
        text-decoration: none;
      }
      #wrapperlicious h1:hover .permalink, #wrapperlicious h2:hover .permalink,
      #wrapperlicious h3:hover .permalink, #wrapperlicious h4:hover .permalink,
      #wrapperlicious dt:hover .permalink {
        display: block;
      }
    </style>
    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-KVNWBNT5FB"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());

      gtag('config', 'G-KVNWBNT5FB');
      gtag('config', 'UA-50555-3');
    </script>
  </head>
  <body>
    <nav class="navbar navbar-expand-md navbar-dark bg-dark justify-content-between">
  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
    <span class="navbar-toggler-icon"></span>
  </button>
  <a class="navbar-brand" href="https://perldoc.perl.org/">Perldoc Browser</a>
  <div class="collapse navbar-collapse" id="navbarNav">
    <ul class="navbar-nav mr-auto">
      <li class="nav-item dropdown text-nowrap">
        <a class="nav-link dropdown-toggle" href="-X.html#" id="dropdownlink-stable" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">5.35.0</a>
        <div class="dropdown-menu" aria-labelledby="dropdownlink-stable">
          <a class="dropdown-item" href="https://perldoc.perl.org/functions/-X">Latest</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.38.2/functions/-X">5.38.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.38.1/functions/-X">5.38.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.38.0/functions/-X">5.38.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.36.3/functions/-X">5.36.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.36.2/functions/-X">5.36.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.36.1/functions/-X">5.36.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.36.0/functions/-X">5.36.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.34.3/functions/-X">5.34.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.34.2/functions/-X">5.34.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.34.1/functions/-X">5.34.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.34.0/functions/-X">5.34.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.32.1/functions/-X">5.32.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.32.0/functions/-X">5.32.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.30.3/functions/-X">5.30.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.30.2/functions/-X">5.30.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.30.1/functions/-X">5.30.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.30.0/functions/-X">5.30.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.28.3/functions/-X">5.28.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.28.2/functions/-X">5.28.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.28.1/functions/-X">5.28.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.28.0/functions/-X">5.28.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.26.3/functions/-X">5.26.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.26.2/functions/-X">5.26.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.26.1/functions/-X">5.26.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.26.0/functions/-X">5.26.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.24.4/functions/-X">5.24.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.24.3/functions/-X">5.24.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.24.2/functions/-X">5.24.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.24.1/functions/-X">5.24.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.24.0/functions/-X">5.24.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.22.4/functions/-X">5.22.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.22.3/functions/-X">5.22.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.22.2/functions/-X">5.22.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.22.1/functions/-X">5.22.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.22.0/functions/-X">5.22.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.20.3/functions/-X">5.20.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.20.2/functions/-X">5.20.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.20.1/functions/-X">5.20.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.20.0/functions/-X">5.20.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.18.4/functions/-X">5.18.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.18.3/functions/-X">5.18.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.18.2/functions/-X">5.18.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.18.1/functions/-X">5.18.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.18.0/functions/-X">5.18.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.16.3/functions/-X">5.16.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.16.2/functions/-X">5.16.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.16.1/functions/-X">5.16.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.16.0/functions/-X">5.16.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.14.4/functions/-X">5.14.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.14.3/functions/-X">5.14.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.14.2/functions/-X">5.14.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.14.1/functions/-X">5.14.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.14.0/functions/-X">5.14.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.12.5/functions/-X">5.12.5</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.12.4/functions/-X">5.12.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.12.3/functions/-X">5.12.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.12.2/functions/-X">5.12.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.12.1/functions/-X">5.12.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.12.0/functions/-X">5.12.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.10.1/functions/-X">5.10.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.10.0/functions/-X">5.10.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.9/functions/-X">5.8.9</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.8/functions/-X">5.8.8</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.7/functions/-X">5.8.7</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.6/functions/-X">5.8.6</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.5/functions/-X">5.8.5</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.4/functions/-X">5.8.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.3/functions/-X">5.8.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.2/functions/-X">5.8.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.1/functions/-X">5.8.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.8.0/functions/-X">5.8.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.6.2/functions/-X">5.6.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.6.1/functions/-X">5.6.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.6.0/functions/-X">5.6.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.005_04/functions/-X">5.005_04</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.005_03/functions/-X">5.005_03</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.005_02/functions/-X">5.005_02</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.005_01/functions/-X">5.005_01</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.005/functions/-X">5.005</a>
        </div>
      </li>
      <li class="nav-item dropdown text-nowrap">
        <a class="nav-link dropdown-toggle" href="-X.html#" id="dropdownlink-dev" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dev</a>
        <div class="dropdown-menu" aria-labelledby="dropdownlink-dev">
          <a class="dropdown-item" href="https://perldoc.perl.org/blead/functions/-X">blead</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.39.6/functions/-X">5.39.6</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.39.5/functions/-X">5.39.5</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.39.4/functions/-X">5.39.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.39.3/functions/-X">5.39.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.39.2/functions/-X">5.39.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.39.1/functions/-X">5.39.1</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.38.0-RC2/functions/-X">5.38.0-RC2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.38.0-RC1/functions/-X">5.38.0-RC1</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.11/functions/-X">5.37.11</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.10/functions/-X">5.37.10</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.9/functions/-X">5.37.9</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.8/functions/-X">5.37.8</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.7/functions/-X">5.37.7</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.6/functions/-X">5.37.6</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.5/functions/-X">5.37.5</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.4/functions/-X">5.37.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.3/functions/-X">5.37.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.2/functions/-X">5.37.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.1/functions/-X">5.37.1</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.37.0/functions/-X">5.37.0</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.11/functions/-X">5.35.11</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.10/functions/-X">5.35.10</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.9/functions/-X">5.35.9</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.8/functions/-X">5.35.8</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.7/functions/-X">5.35.7</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.6/functions/-X">5.35.6</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.5/functions/-X">5.35.5</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.4/functions/-X">5.35.4</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.3/functions/-X">5.35.3</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.2/functions/-X">5.35.2</a>
          <a class="dropdown-item" href="https://perldoc.perl.org/5.35.1/functions/-X">5.35.1</a>
          <a class="dropdown-item active" href="-X.html">5.35.0</a>
        </div>
      </li>
      <li class="nav-item dropdown text-nowrap">
        <a class="nav-link dropdown-toggle" href="-X.html#" id="dropdownlink-nav" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Documentation</a>
        <div class="dropdown-menu" aria-labelledby="dropdownlink-nav">
          <a class="dropdown-item" href="../perl.html">Perl</a>
          <a class="dropdown-item" href="../perlintro.html">Intro</a>
          <a class="dropdown-item" href="../perl.html#Tutorials">Tutorials</a>
          <a class="dropdown-item" href="../perlfaq.html">FAQs</a>
          <a class="dropdown-item" href="../perl.html#Reference-Manual">Reference</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="../perlop.html">Operators</a>
          <a class="dropdown-item" href="../functions.html">Functions</a>
          <a class="dropdown-item" href="../variables.html">Variables</a>
          <a class="dropdown-item" href="../modules.html">Modules</a>
          <a class="dropdown-item" href="../perlutil.html">Utilities</a>
          <div class="dropdown-divider"></div>
          <a class="dropdown-item" href="../perlcommunity.html">Community</a>
          <a class="dropdown-item" href="../perlhist.html">History</a>
        </div>
      </li>
    </ul>
    <ul class="navbar-nav">
      <script>
        function set_expand (expand) {
          var perldocdiv = document.getElementById('perldocdiv');
          var width = window.getComputedStyle(perldocdiv).getPropertyValue('max-width');
          var expanded = (width == '' || width == 'none') ? true : false;
          if (expand === null) {
            expand = !expanded;
          }
          if ((expand && !expanded) || (!expand && expanded)) {
            perldocdiv.style.setProperty('max-width', expand ? 'none' : '960px');
            var button_classlist = document.getElementById('content-expand-button').classList;
            if (expand) {
              button_classlist.add('btn-light');
              button_classlist.remove('btn-outline-light');
            } else {
              button_classlist.add('btn-outline-light');
              button_classlist.remove('btn-light');
            }
          }
          return expand;
        }
        function toggle_expand () {
          var expand = set_expand(null);
          document.cookie = 'perldoc_expand=' + (expand ? 1 : 0) + '; path=/; expires=Tue, 19 Jan 2038 03:14:07 UTC';
        }
        function read_expand () {
          return document.cookie.split(';').some(function (item) { return item.indexOf('perldoc_expand=1') >= 0 });
        }
        if (document.readyState === 'loading') {
          document.addEventListener('DOMContentLoaded', function () {
            if (read_expand()) {
              set_expand(true);
            }
          });
        } else if (read_expand()) {
          set_expand(true);
        }
      </script>
      <button id="content-expand-button" type="button" class="btn btn-outline-light d-none d-lg-inline-block mr-2" onclick="toggle_expand()">Expand</button>
    <ul>
    <form class="form-inline" method="get" action="https://perldoc.perl.org/5.35.0/search">
      <input class="form-control mr-3" type="search" name="q" placeholder="Search" aria-label="Search">
    </form>
  </div>
</nav>

    <div id="wrapperlicious" class="container-fluid">
      <div id="perldocdiv">
        <div id="links">
          <a href="../functions.html">functions</a>
            / <a href="-X.html">-X</a>
          <div id="more">
            (<a href="-X.txt">source</a>,
            <a href="CORE.html#-X-FILEHANDLE">CPAN</a>)
          </div>
        </div>
        <div class="leading-notice">
          You are viewing the version of this documentation from Perl 5.35.0.
            This is a development version of Perl.
        </div>
      <dl>

<dt id="-X-FILEHANDLE"><a class="permalink" href="-X.html#-X-FILEHANDLE">#</a><a id="X-FILEHANDLE"></a>-X FILEHANDLE  </dt>
<dd>

</dd>
<dt id="-X-EXPR"><a class="permalink" href="-X.html#-X-EXPR">#</a><a id="X-EXPR"></a>-X EXPR</dt>
<dd>

</dd>
<dt id="-X-DIRHANDLE"><a class="permalink" href="-X.html#-X-DIRHANDLE">#</a><a id="X-DIRHANDLE"></a>-X DIRHANDLE</dt>
<dd>

</dd>
<dt id="-X"><a class="permalink" href="-X.html#-X">#</a><a id="X"></a>-X</dt>
<dd>

<p>A file test, where X is one of the letters listed below. This unary operator takes one argument, either a filename, a filehandle, or a dirhandle, and tests the associated file to see if something is true about it. If the argument is omitted, tests <a href="../perlvar.html#%24_"><code>$_</code></a>, except for <code>-t</code>, which tests STDIN. Unless otherwise documented, it returns <code>1</code> for true and <code>&#39;&#39;</code> for false. If the file doesn&#39;t exist or can&#39;t be examined, it returns <a href="undef.html"><code>undef</code></a> and sets <a href="../perlvar.html#%24%21"><code>$!</code></a> (errno). With the exception of the <code>-l</code> test they all follow symbolic links because they use <code>stat()</code> and not <code>lstat()</code> (so dangling symlinks can&#39;t be examined and will therefore report failure).</p>

<p>Despite the funny names, precedence is the same as any other named unary operator. The operator may be any of:</p>

<pre><code class="plaintext">    -r  File is readable by effective uid/gid.
    -w  File is writable by effective uid/gid.
    -x  File is executable by effective uid/gid.
    -o  File is owned by effective uid.

    -R  File is readable by real uid/gid.
    -W  File is writable by real uid/gid.
    -X  File is executable by real uid/gid.
    -O  File is owned by real uid.

    -e  File exists.
    -z  File has zero size (is empty).
    -s  File has nonzero size (returns size in bytes).

    -f  File is a plain file.
    -d  File is a directory.
    -l  File is a symbolic link (false if symlinks aren&#39;t
        supported by the file system).
    -p  File is a named pipe (FIFO), or Filehandle is a pipe.
    -S  File is a socket.
    -b  File is a block special file.
    -c  File is a character special file.
    -t  Filehandle is opened to a tty.

    -u  File has setuid bit set.
    -g  File has setgid bit set.
    -k  File has sticky bit set.

    -T  File is an ASCII or UTF-8 text file (heuristic guess).
    -B  File is a &quot;binary&quot; file (opposite of -T).

    -M  Script start time minus file modification time, in days.
    -A  Same for access time.
    -C  Same for inode change time (Unix, may differ for other
	platforms)</code></pre>

<p>Example:</p>

<pre><code>while (&lt;&gt;) {
    chomp;
    next unless -f $_;  # ignore specials
    #...
}</code></pre>

<p>Note that <code>-s/a/b/</code> does not do a negated substitution. Saying <code>-exp($foo)</code> still works as expected, however: only single letters following a minus are interpreted as file tests.</p>

<p>These operators are exempt from the &quot;looks like a function rule&quot; described above. That is, an opening parenthesis after the operator does not affect how much of the following code constitutes the argument. Put the opening parentheses before the operator to separate it from code that follows (this applies only to operators with higher precedence than unary operators, of course):</p>

<pre><code>-s($file) + 1024   # probably wrong; same as -s($file + 1024)
(-s $file) + 1024  # correct</code></pre>

<p>The interpretation of the file permission operators <code>-r</code>, <code>-R</code>, <code>-w</code>, <code>-W</code>, <code>-x</code>, and <code>-X</code> is by default based solely on the mode of the file and the uids and gids of the user. There may be other reasons you can&#39;t actually read, write, or execute the file: for example network filesystem access controls, ACLs (access control lists), read-only filesystems, and unrecognized executable formats. Note that the use of these six specific operators to verify if some operation is possible is usually a mistake, because it may be open to race conditions.</p>

<p>Also note that, for the superuser on the local filesystems, the <code>-r</code>, <code>-R</code>, <code>-w</code>, and <code>-W</code> tests always return 1, and <code>-x</code> and <code>-X</code> return 1 if any execute bit is set in the mode. Scripts run by the superuser may thus need to do a <a href="stat.html"><code>stat</code></a> to determine the actual mode of the file, or temporarily set their effective uid to something else.</p>

<p>If you are using ACLs, there is a pragma called <a href="../filetest.html"><code>filetest</code></a> that may produce more accurate results than the bare <a href="stat.html"><code>stat</code></a> mode bits. When under <code>use filetest &#39;access&#39;</code>, the above-mentioned filetests test whether the permission can(not) be granted using the <a href="http://man.he.net/man2/access">access(2)</a> family of system calls. Also note that the <code>-x</code> and <code>-X</code> tests may under this pragma return true even if there are no execute permission bits set (nor any extra execute permission ACLs). This strangeness is due to the underlying system calls&#39; definitions. Note also that, due to the implementation of <code>use filetest &#39;access&#39;</code>, the <code>_</code> special filehandle won&#39;t cache the results of the file tests when this pragma is in effect. Read the documentation for the <a href="../filetest.html"><code>filetest</code></a> pragma for more information.</p>

<p>The <code>-T</code> and <code>-B</code> tests work as follows. The first block or so of the file is examined to see if it is valid UTF-8 that includes non-ASCII characters. If so, it&#39;s a <code>-T</code> file. Otherwise, that same portion of the file is examined for odd characters such as strange control codes or characters with the high bit set. If more than a third of the characters are strange, it&#39;s a <code>-B</code> file; otherwise it&#39;s a <code>-T</code> file. Also, any file containing a zero byte in the examined portion is considered a binary file. (If executed within the scope of a <a href="../perllocale.html"><span style="white-space: nowrap;">use locale</span></a> which includes <code>LC_CTYPE</code>, odd characters are anything that isn&#39;t a printable nor space in the current locale.) If <code>-T</code> or <code>-B</code> is used on a filehandle, the current IO buffer is examined rather than the first block. Both <code>-T</code> and <code>-B</code> return true on an empty file, or a file at EOF when testing a filehandle. Because you have to read a file to do the <code>-T</code> test, on most occasions you want to use a <code>-f</code> against the file first, as in <code>next unless -f $file &amp;&amp; -T $file</code>.</p>

<p>If any of the file tests (or either the <a href="stat.html"><code>stat</code></a> or <a href="lstat.html"><code>lstat</code></a> operator) is given the special filehandle consisting of a solitary underline, then the stat structure of the previous file test (or <a href="stat.html"><code>stat</code></a> operator) is used, saving a system call. (This doesn&#39;t work with <code>-t</code>, and you need to remember that <a href="lstat.html"><code>lstat</code></a> and <code>-l</code> leave values in the stat structure for the symbolic link, not the real file.) (Also, if the stat buffer was filled by an <a href="lstat.html"><code>lstat</code></a> call, <code>-T</code> and <code>-B</code> will reset it with the results of <code>stat _</code>). Example:</p>

<pre><code>print &quot;Can do.\n&quot; if -r $a || -w _ || -x _;

stat($filename);
print &quot;Readable\n&quot; if -r _;
print &quot;Writable\n&quot; if -w _;
print &quot;Executable\n&quot; if -x _;
print &quot;Setuid\n&quot; if -u _;
print &quot;Setgid\n&quot; if -g _;
print &quot;Sticky\n&quot; if -k _;
print &quot;Text\n&quot; if -T _;
print &quot;Binary\n&quot; if -B _;</code></pre>

<p>As of Perl 5.10.0, as a form of purely syntactic sugar, you can stack file test operators, in a way that <code>-f -w -x $file</code> is equivalent to <code>-x $file &amp;&amp; -w _ &amp;&amp; -f _</code>. (This is only fancy syntax: if you use the return value of <code>-f $file</code> as an argument to another filetest operator, no special magic will happen.)</p>

<p>Portability issues: <a href="../perlport.html#-X">&quot;-X&quot; in perlport</a>.</p>

<p>To avoid confusing would-be users of your code with mysterious syntax errors, put something like this at the top of your script:</p>

<pre><code>use 5.010;  # so filetest ops can stack</code></pre>

</dd>
</dl>


      </div>
      <div id="footer">
        <p>Perldoc Browser is maintained by Dan Book (<a href="https://metacpan.org/author/DBOOK">DBOOK</a>). Please contact him via the <a href="https://github.com/Grinnz/perldoc-browser/issues">GitHub issue tracker</a> or <a href="mailto:dbook@cpan.org">email</a> regarding any issues with the site itself, search, or rendering of documentation.</p>

<p>The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via the <a href="https://github.com/Perl/perl5/issues">Perl issue tracker</a>, the <a href="https://lists.perl.org/list/perl5-porters.html">mailing list</a>, or <a href="https://kiwiirc.com/client/irc.perl.org/p5p">IRC</a> to report any issues with the contents or format of the documentation.</p>


      </div>
    </div>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.slim.min.js" integrity="sha512-/DXTXr6nQodMUiq+IUJYCt2PPOUjrHJ9wFrqpJ3XkgPNOZVfMok7cRw6CSxyCQxXn6ozlESsSh1/sMCTF1rL/g==" crossorigin="anonymous"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.16.1/umd/popper.min.js" integrity="sha512-ubuT8Z88WxezgSqf3RLuNi5lmjstiJcyezx34yIU2gAHonIi27Na7atqzUZCOoY4CExaoFumzOsFQ2Ch+I/HCw==" crossorigin="anonymous"></script>
    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js" integrity="sha384-B4gt1jrGC7Jh4AgTPSdUtOBvfO8shuf57BaghqFfPlYxofvL8/KUEfYiJOMMV+rV" crossorigin="anonymous"></script>
    <script src="../../highlight.pack.js"></script>
    <script>hljs.highlightAll();</script>
  </body>
</html>
